home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat2 / standard / arsctl.z / arsctl
Encoding:
Text File  |  2001-04-17  |  15.7 KB  |  265 lines
  1.  
  2.  
  3.  
  4. aaaarrrrssssccccttttllll((((2222))))                                                            aaaarrrrssssccccttttllll((((2222))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      arsctl - modify the behavior of array sessions
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ####iiiinnnncccclllluuuuddddeeee <<<<ssssyyyyssss////aaaarrrrsssseeeessssssss....hhhh>>>>
  13.  
  14.      iiiinnnntttt aaaarrrrssssccccttttllll((((iiiinnnntttt ffffuuuunnnncccc,,,, vvvvooooiiiidddd ****bbbbuuuuffffppppttttrrrr,,,, iiiinnnntttt bbbbuuuufffflllleeeennnn))));;;;
  15.  
  16. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  17.      The _a_r_s_c_t_l function queries and/or modifies some aspect of the behavior
  18.      of array sessions on the currently running system.
  19.  
  20.      Most of the array session control operations take some sort of argument.
  21.      A pointer to the argument is passed as _b_u_f_p_t_r, and the length of the
  22.      argument is specified with _b_u_f_l_e_n.
  23.  
  24.      The particular operation to be performed is identified by the function
  25.      code _f_u_n_c, which is defined in <_s_y_s/_a_r_s_e_s_s._h>.  Available array session
  26.      control operations include:
  27.  
  28.      AAAARRRRSSSSCCCCTTTTLLLL____GGGGEEEETTTTDDDDFFFFLLLLTTTTSSSSPPPPIIIILLLLEEEENNNN
  29.             Returns the number of bytes of storage that is allocated for
  30.             Service Provider Information in new array sessions.  The value is
  31.             stored as an _i_n_t at the location specified by _b_u_f_p_t_r.  The default
  32.             value at system initialization time is determined by the kernel
  33.             variable _s_p_i_l_e_n, which can be modified using _s_y_s_t_u_n_e(1M).
  34.  
  35.      AAAARRRRSSSSCCCCTTTTLLLL____SSSSEEEETTTTDDDDFFFFLLLLTTTTSSSSPPPPIIIILLLLEEEENNNN
  36.             Sets the number of bytes of storage that is allocated for Service
  37.             Provider Information in new array sessions to the value contained
  38.             in the _i_n_t pointed to by _b_u_f_p_t_r.  An EEEEIIIINNNNVVVVAAAALLLL error will occur if
  39.             the value is negative or is greater than the system maximum value
  40.             (typically 1024), and the current setting will remain unchanged.
  41.             Existing array sessions are not affected by this change, nor is
  42.             the setting of the kernel variable _s_p_i_l_e_n.  The caller must be
  43.             privileged to use this function.
  44.  
  45.      AAAARRRRSSSSCCCCTTTTLLLL____GGGGEEEETTTTSSSSAAAAFFFF
  46.             Returns the session accounting record format.  The value is stored
  47.             as an _i_n_t at the location specified by _b_u_f_p_t_r.  The default value
  48.             at system initialization time is determined by the kernel variable
  49.             _s_e_s_s_a_f, which can be modified using _s_y_s_t_u_n_e(1M).
  50.  
  51.      AAAARRRRSSSSCCCCTTTTLLLL____SSSSEEEETTTTSSSSAAAAFFFF
  52.             Sets the session accounting record format to the value contained
  53.             in the _i_n_t pointed to by _b_u_f_p_t_r.  Any subsequent session
  54.             accounting records that are generated by the kernel will be in the
  55.             specified format.  An EEEEIIIINNNNVVVVAAAALLLL error will occur if an invalid format
  56.             number is specified, and the current setting will remain
  57.             unchanged.  The caller must be privileged to use this function.
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. aaaarrrrssssccccttttllll((((2222))))                                                            aaaarrrrssssccccttttllll((((2222))))
  71.  
  72.  
  73.  
  74.      AAAARRRRSSSSCCCCTTTTLLLL____GGGGEEEETTTTMMMMAAAACCCCHHHHIIIIDDDD
  75.             Returns the current machine ID.  The machine ID is an arbitrary
  76.             value used by the kernel in the generation of array session
  77.             handles.  It is intended to uniquely identify a machine within a
  78.             particular array/cluster configuration.  The value is stored as an
  79.             _i_n_t at the location specified by _b_u_f_p_t_r.  The default value at
  80.             system initialization time is determined by the kernel variable
  81.             _a_s_m_a_c_h_i_d, which can be modified using _s_y_s_t_u_n_e(1M).
  82.  
  83.      AAAARRRRSSSSCCCCTTTTLLLL____SSSSEEEETTTTMMMMAAAACCCCHHHHIIIIDDDD
  84.             Sets the machine ID to the value contained in the _i_n_t pointed to
  85.             by _b_u_f_p_t_r.  Any subsequent array session handles that are
  86.             generated by the kernel may incorporate this value in some way.  A
  87.             machine ID is normally a positive integer in the range 1-32767.
  88.             In an array/cluster configuration, no two machines should have the
  89.             same machine ID.  If a machine ID of 0 is specified, any
  90.             subsequent array session handles generated by the kernel will be
  91.             "local"; this means that the machine and array ID's will not be
  92.             incorporated into the array session handle, and its uniqueness in
  93.             an array/cluster configuration is not guaranteed.  If a machine ID
  94.             of -1 is specified, then the default machine ID specified by the
  95.             kernel variable _a_s_m_a_c_h_i_d will be used instead.  If any other value
  96.             is specified for the machine ID, an EEEEIIIINNNNVVVVAAAALLLL error will occur and
  97.             the machine ID will remain unchanged.  The caller must be
  98.             privileged to use this function.
  99.  
  100.      AAAARRRRSSSSCCCCTTTTLLLL____GGGGEEEETTTTAAAARRRRRRRRAAAAYYYYIIIIDDDD
  101.             Returns the current array ID.  The array ID is an arbitrary value
  102.             used by the kernel in the generation of array session handles.  If
  103.             a particular machine were a member of more than one array or
  104.             cluster, the array ID would typically identify which array the
  105.             array session was associated with, if any.  The value is stored as
  106.             an _i_n_t at the location specified by _b_u_f_p_t_r.  The default value at
  107.             system initialization time is determined by the kernel variable
  108.             _a_s_a_r_r_a_y_i_d, which can be modified using _s_y_s_t_u_n_e(1M).
  109.  
  110.      AAAARRRRSSSSCCCCTTTTLLLL____SSSSEEEETTTTAAAARRRRRRRRAAAAYYYYIIIIDDDD
  111.             Sets the array ID to the value contained in the _i_n_t pointed to by
  112.             _b_u_f_p_t_r.  Any subsequent array session handles that are generated
  113.             by the kernel may incorporate this value in some way.  An array ID
  114.             is an integer in the range 0-65535.  If a value of -1 is
  115.             specified, then the default array ID specified by the kernel
  116.             variable _a_s_a_r_r_a_y_i_d will be used instead.  If any other value
  117.             outside of this range is specified, an EEEEIIIINNNNVVVVAAAALLLL error will occur and
  118.             the array ID will remain unchanged.  The values 0-65534 (0-0xfffe)
  119.             are normally reserved for array services (see _a_r_r_a_y__s_e_r_v_i_c_e_s(5)),
  120.             so if array services are in use on a system, the only appropriate
  121.             array ID for the kernel is 65535 (0xffff).  The caller must be
  122.             privileged to use this function.
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. aaaarrrrssssccccttttllll((((2222))))                                                            aaaarrrrssssccccttttllll((((2222))))
  137.  
  138.  
  139.  
  140.      AAAARRRRSSSSCCCCTTTTLLLL____GGGGEEEETTTTAAAASSSSHHHHCCCCTTTTRRRR
  141.             Returns the current value of the counter used to form the local
  142.             portion of the next array session handle.  The value is stored as
  143.             an _a_s_h__t at the location specified by _b_u_f_p_t_r.  Notice that the
  144.             counter could potentially be incremented at any time by any other
  145.             CPU in the system, so the returned value must be considered a mere
  146.             "snapshot" of the value at the instant that the function was
  147.             processed.
  148.  
  149.      AAAARRRRSSSSCCCCTTTTLLLL____SSSSEEEETTTTAAAASSSSHHHHCCCCTTTTRRRR
  150.             Sets the counter that is used by the kernel to form the local
  151.             portion of array session handles to the value contained in the
  152.             _a_s_h__t pointed to by _b_u_f_p_t_r.  Any subsequent array session handles
  153.             that are generated by the kernel may incorporate this value in
  154.             some way.  The valid range of values is determined by the kernel
  155.             variables _m_i_n__l_o_c_a_l__p_a_g_g_i_d and _m_a_x__l_o_c_a_l__p_a_g_g_i_d.  If a value
  156.             outside of this range is specified, an EEEEIIIINNNNVVVVAAAALLLL error will occur and
  157.             the counter will remain unchanged.  The caller must be privileged
  158.             to use this function.
  159.  
  160.      AAAARRRRSSSSCCCCTTTTLLLL____GGGGEEEETTTTAAAASSSSHHHHIIIINNNNCCCCRRRR
  161.             Returns the current increment value for the counter used to form
  162.             the local portion of the next array session handle.  The value is
  163.             stored as an _a_s_h__t at the location specified by _b_u_f_p_t_r.
  164.  
  165.      AAAARRRRSSSSCCCCTTTTLLLL____SSSSEEEETTTTAAAASSSSHHHHIIIINNNNCCCCRRRR
  166.             Sets the increment for the counter that is used by the kernel to
  167.             form the local portion of array session handles to the value
  168.             contained in the _a_s_h__t pointed to by _b_u_f_p_t_r.  The specified value
  169.             will be added to this counter after the next and subsequent array
  170.             session handles are generated by the kernel.  The value may be
  171.             positive or negative but it may not be zero, and its absolute
  172.             value must be less than the difference between the kernel
  173.             variables _m_a_x__l_o_c_a_l__p_a_g_g_i_d and _m_i_n__l_o_c_a_l__p_a_g_g_i_d.  If an illegal
  174.             value is specified, an EEEEIIIINNNNVVVVAAAALLLL error will occur and the increment
  175.             value will remain unchanged.  The caller must be privileged to use
  176.             this function.
  177.  
  178.      AAAARRRRSSSSCCCCTTTTLLLL____GGGGEEEETTTTDDDDFFFFLLLLTTTTSSSSPPPPIIII
  179.             Stores the default Service Provider Information into the buffer
  180.             pointed to by _b_u_f_p_t_r.  This information is considered to be
  181.             associated with any array session that has neither specifically
  182.             set its service provider information, nor is descended from an
  183.             array session that has done so.  If the argument buffer is too
  184.             small to accommodate all of the service provider information, the
  185.             data will be truncated.  If the argument buffer is larger than the
  186.             service provider information the data will be padded on the right
  187.             with zeroes.
  188.  
  189.      AAAARRRRSSSSCCCCTTTTLLLL____SSSSEEEETTTTDDDDFFFFLLLLTTTTSSSSPPPPIIII
  190.             Sets the default Service Provider Information to the contents of
  191.             the buffer pointed to by _b_u_f_p_t_r.  This information will
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. aaaarrrrssssccccttttllll((((2222))))                                                            aaaarrrrssssccccttttllll((((2222))))
  203.  
  204.  
  205.  
  206.             immediately become associated with all array sessions that have
  207.             neither specifically set their service provider information, nor
  208.             are descended from an array session that has done so.  The size of
  209.             the service provider information should ordinarily be the same as
  210.             whatever is returned by the AAAARRRRSSSSCCCCTTTTLLLL____GGGGEEEETTTTSSSSPPPPIIIILLLLEEEENNNN function.  If the
  211.             argument buffer is too small, the service provider information
  212.             will be padded on the right with zeroes.  If the argument buffer
  213.             is too large, an EEEEIIIINNNNVVVVAAAALLLL error will occur and the default service
  214.             provider information will remain unchanged.  The caller must be
  215.             privileged to use this function.
  216.  
  217.      AAAARRRRSSSSCCCCTTTTLLLL____AAAALLLLLLLLOOOOCCCCAAAASSSSHHHH
  218.             Allocates an unused array session handle and stores it into the
  219.             buffer pointed to by _b_u_f_p_t_r.  _b_u_f_l_e_n must be equal to
  220.             ssssiiiizzzzeeeeooooffff((((aaaasssshhhh____tttt)))) or else an EEEEIIIINNNNVVVVAAAALLLL error will occur.  The ASH that is
  221.             allocated by this function is guaranteed not to be in use on the
  222.             local system at the time it was allocated.  Furthermore, under
  223.             normal circumstances the allocated ASH will not be reallocated by
  224.             the local system until the "ASH counter" (see AAAARRRRSSSSCCCCTTTTLLLL____GGGGEEEETTTTAAAASSSSHHHHCCCCTTTTRRRR and
  225.             AAAARRRRSSSSCCCCTTTTLLLL____SSSSEEEETTTTAAAASSSSHHHHCCCCTTTTRRRR) has incremented through its entire range of
  226.             values and once again returns to the value that was used for the
  227.             allocated ASH.  Exceptions to this would include rebooting the
  228.             system (which will ordinarily return the ASH counter to its
  229.             minimum value) and manual changes to the ASH counter using the
  230.             AAAARRRRSSSSCCCCTTTTLLLL____SSSSEEEETTTTAAAASSSSHHHHCCCCTTTTRRRR function.
  231.  
  232. EEEERRRRRRRROOOORRRRSSSS
  233.      _a_r_s_c_t_l may fail if one or more of these conditions are true:
  234.  
  235.      EEEEFFFFAAAAUUUULLLLTTTT    _b_u_f_p_t_r is not a valid address.
  236.  
  237.      EEEEIIIINNNNVVVVAAAALLLL    _f_u_n_c is not a valid function code.
  238.  
  239.      EEEEIIIINNNNVVVVAAAALLLL    _b_u_f_l_e_n is the wrong size for the given function code.
  240.  
  241.      EEEEIIIINNNNVVVVAAAALLLL    The argument pointed to by _b_u_f_p_t_r is not valid.
  242.  
  243.      EEEEPPPPEEEERRRRMMMM     The current process does not have the appropriate privileges to
  244.                perform the operation specified by _f_u_n_c.
  245.  
  246. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  247.      systune(1M), arsop(2), extacct(4), array_sessions(5).
  248.  
  249. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  250.      Upon successful completion, _a_r_s_c_t_l returns a value of 0.  Otherwise, a
  251.      value of -1 is returned and _e_r_r_n_o is set to indicate the error.
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.